DragWithin

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODPart

DragWithin
The DragWithin method should track a drag operation and provide graphical feedback regarding possible drop targets.
ODDragResult DragWithin (in ODDragItemIterator dragInfo,
                         in ODFacet facet,
                         in ODPoint where);
dragInfo
A reference to a drag-item iterator that describes the content, as well as the types and values, of the dragged data.
facet
A reference to a facet where the drag point is located.
where
The location of the drag point, expressed in frame coordinates.
return value
kODTrue if this part accepts drag-and-drop events in its display frame, otherwise kODFalse.

DISCUSSION
Your part's DragWithin method allows your part to do any desired processing inside of its display frame. For example, if your part allows objects to be dropped only on individual hot spots, it may change its feedback based on mouse-pointer location. If the mouse is not over these hot spots, the cursor may need to be changed to reflect that no dropping can be done, even though the mouse is in a droppable frame. OpenDoc calls this method continuously when the drag point is within the borders of the specified facet's frame.
Your part's DragWithin method should examine the part kinds of the dragged data (using the drag-item iterator specified by the dragInfo parameter) and determine whether it can accept the dragged data. Your part should not at this point attempt to read data from any of the storage units supplied by the drag-item iterator. If your part can accept a drop, it should provide the appropriate feedback to the user, for example, by displaying its drag border or changing the cursor appearance. If your part cannot handle the part kinds of the dragged data, it should take no action. If your part's DragWithin method returns kODFalse, OpenDoc assumes you no longer wish to accept a drop in this facet. It will not make additional calls to your DragWithin or Drop methods as long as the mouse pointer remains in this facet. In addition, if your part calls one of its display frames' SetDroppable method with a value of kODTrue, you must override this method and implement the protocol for drag highlighting and accepting dropped data.
Your part's DragWithin method also represents an opportunity for your part to examine the state of the machine. For example, some parts may want to know whether the modifier keys are down while a drag operation is in progress.

OVERRIDING
When you subclass ODPart, you can override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.

EXCEPTIONS

kODErrDoesNotDrop
This part does not support drag and drop.

SEE ALSO
The ODDragResult type (page 922).
The ODPoint type (page 885).
The ODFrame::SetDroppable method (page 333).
The ODPart::DragEnter method (page 500).
The ODPart::DragLeave method (page 502).
Table 2-1 on page 89 in OpenDoc Programmer's Guide.
"While Within a Part's Facet" on page 363 in OpenDoc Programmer's Guide.
"Dropping" on page 364 in OpenDoc Programmer's Guide.